September 27th, 2012

About

This is the eighth source code release of Ilios 2 (version 2.1.0).

The changelist of notables is maintained in a parallel file named CHANGELOG.txt.

Please keep up to date, and feel free to contact us via any of the following:

• the Ilios 2 website

• the project's SourceForge Forums

Thanks from the Ilios 2 Team.

Installation

Prerequisites and Dependencies

The Ilios 2 server side code relies upon the following:

• Apache 2.2.3+ or IIS 6+

• PHP 5.3.3+, with mysqli support.

  Note: short tags must be turned on in the PHP configuration (short_open_tag = On)

• MySQL 5.0.77 or later, with support for both InnoDB and MyISAM

  Note: MySQL must NOT run in strict SQL mode.

Configuration files

The application configuration is maintained within the following files:

system/application/config/config.php   ... contains general web-application configuration
system/application/config/ilios.php    ... contains Ilios-specific configuration
system/application/config/database.php ... contains the database configuration

Deployment

Ilios 2 uses the CodeIgniter framework and, as such, has its directory structure laid out in usual CodeIgniter structure.

The minimal steps to get an Ilios 2 deployment running are not that great and can be described as the following:

1. Copy the Ilios 2 release tar ball into the root directory of your web server (or whatever subdirectory you wish)

2. Unpack the tarball

3. Change file permissions appropriately. The following directories need to be able to be written to by your Apache process:

   learning_materials
   tmp_uploads
   system/logs
   

4. Configure the following files to reflect your institution's name, appropriate URLs, and database attributes:

   index.php                               ... substitute placeholder token with your URL
   system/application/config/config.php    ... substitute placeholder token with your URL
   system/application/config/ilios.php     ... set your institution's name and authentication method
   system/application/config/database.php  ... fill in your database connection settings
   

5. Construct and populate your database as described below

6. Run the script found in the root directory called: install_user_zero.sh

7. If you need to turn on Shibboleth protection -- detailed more below.

8. Ilios 2 should now be ready for use.

Data setup and data import

The database must be created using latin1_swedish_ci as default collation and latin1 as default character set.

The database may be constructed by source-ing the table schemas, stored procedures and stored functions SQL.

Thereafter, you may ingest the 2010 MeSH universe SQL.

To create the needed tables, stored procedures/functions and triggers for Ilios2, source the following the SQL files:

database/ilios2_tables.sql
database/ilios2_stored.sql
database/ilios2_triggers.sql

Once you've done this, you should populate the following tables appropriately (an example population exists in database/data_population):

alert_change_type
competency
discipline
learning_material_status
learning_material_user_role
school
department
session_type
user_role

Extract the mesh_tables_and_data.sql.gz file containing the 2010 MeSH universe SQL. It can be found in the database/data_population directory.

Alternatively, download the MeSH XML of your choosing, ant compile the source code in ilios2_mesh_parser.tar.gz and run the resulting Java program against the XML file to populate your MeSH databases.

Shortcut alternative

You may source the utility script database/make_new_i2_database.sql to set up the db schema and to ingest the data population/mesh universe in one step. Please read the code comments within the file and replace the placeholder for the database name accordingly before sourcing the script!

Also, please note that you still must extract the zip-file containing the MeSH universe manually.

Upgrading

Deploy code and configuration changes

The least painful way to upgrade from the previous version would likely be to copy the following items out of the way:

index.php
learning_materials
tmp_uploads
system/application/config/config.php
system/application/config/database.php

Then backup all data of course, and next unpack the new tarball over the pre-existing install.

Copy back the above listed assets, also noting any changes to the files listed at the top of this document (like system/application/config/config.php) which need be included in your older version.

ACHTUNG!

With the release of v2.1.0, a large chunk of Ilios-specific settings have been moved to system/application/config/ilios.php.

If you are upgrading from v2.0.7b or older please make sure to reconcile the differences between your old config.php file and the new config.php/ilios.php.

Deploy database changes

Run the SQL commands specified in database/_DB_UPGRADE.sql on your Ilios database that apply to the range of versions that you are upgrading from/to. Back up your database first before running any upgrade scripts against it!

Security and Authentication

Starting with v2.1.0, Ilios now ships with an authentication-system based on an internal user- and user-credentials store. This authentication method is the default; no patching is required to activate.

If you want to use Shibboleth as authentication-system you must explicitly set the appropriate configuration setting.

Ilios-internal Authentication

If you are setting up an Ilios instance from scratch, it is highly recommended that you provide a salt to increase the security of user passwords.

You may do so by assigning a value to the $config['ilios_authentication_internal_auth_salt'] setting in system/application/config/ilios.php.

Shibboleth Authentication

In system/application/config/ilios.php, change the authentication method to shibboleth

$config['ilios_authentication'] = 'shibboleth';

We recommend the following exposure scheme; this is assuming Ilios2 is installed at the web-root:

<Location />
  AuthType shibboleth
  ShibRequestSetting requireSession 1
  require valid-user
</Location>

<LocationMatch /$>
  Satisfy Any
  Allow from all
</LocationMatch>

<LocationMatch "/ilios2.php/([^/]+)/getI18NJavascriptVendor">
  Satisfy Any
  Allow from all
</LocationMatch>

<Location /index.php>
  Satisfy Any
  Allow from all
</Location>

<Location /images>
  Satisfy Any
  Allow from all
</Location>

<Location /system/application/views/scripts>
  Satisfy Any
  Allow from all
</Location>

<Location /system/application/views/images>
  Satisfy Any
  Allow from all
</Location>

<Location /system/application/views/css>
  Satisfy Any
  Allow from all
</Location>

<Location /favicon.ico>
  Satisfy Any
  Allow from all
</Location>

<Location /version.php>
  Satisfy Any
  Allow from all
</Location>